---
title: "Errors"
description: "Error structure and handling in the Agent Communication Protocol"
---

The **Agent Communication Protocol (ACP)** provides a consistent error structure to make error handling easier for both clients and servers.

## Error structure
Each error contains:
- **Code**: A predefined identifier for programmatic handling
- **Message**: A human-readable description for display or logging

Use codes to drive error-handling logic and messages for user display or logging. See the [specification](https://github.com/i-am-bee/acp/blob/main/docs/spec/openapi.yaml) for the current set of error codes.


## Error handling

Servers can send errors in three ways:
- HTTP response body (failed requests)
- Within a failed run
- As events in a stream error

Clients must monitor all these locations and handle errors appropriately.

SDK clients should expose errors in a way that's natural for the programming language, typically as exceptions:

<Tabs>
    <Tab title="Python">
        ```python
        try:
            run = await client.run_sync(...)
            run.raise_for_status()
        except ACPError as e:
            error = e.error
            # Logic that handles the error
        ```
    </Tab>
</Tabs>

### Guidance

When handling errors:
- Use the **code** for programmatic decisions
- Use the **message** for display or logging
- Tailor your response to your application type

**Example**: A chat UI should show invalid_input error messages to users, but log server_error messages to the console (since they may be too technical). A CLI would likely display all error messages regardless of code.